feat: add `fmt_engineering()` #786

rich-iannone · 2025-10-20T01:04:40Z

This PR adds the .fmt_engineering() formatting method. Engineering notation expresses values so that they align to certain SI prefixes. Here is a table that compares select SI prefixes and their symbols to decimal and engineering-notation representations of key numbers.

import polars as pl
from great_tables import GT

prefixes_df = pl.DataFrame({
    "name": [
        "peta", "tera", "giga", "mega", "kilo",
        None,
        "milli", "micro", "nano", "pico", "femto"
    ],
    "symbol": [
        "P", "T", "G", "M", "k",
        None,
        "m", "μ", "n", "p", "f"
    ],
    "decimal": [float(10**i) for i in range(15, -18, -3)],
})

prefixes_df = prefixes_df.with_columns(
    engineering=pl.col("decimal")
)

(
    GT(prefixes_df)
    .fmt_number(columns="decimal", n_sigfig=1)
    .fmt_engineering(columns="engineering")
    .sub_missing()
)

Fixes: #785

codecov · 2025-10-20T01:06:35Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.77%. Comparing base (c86242f) to head (0692903).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #786      +/-   ##
==========================================
+ Coverage   91.61%   91.77%   +0.15%     
==========================================
  Files          47       47              
  Lines        5773     5821      +48     
==========================================
+ Hits         5289     5342      +53     
+ Misses        484      479       -5

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

machow · 2026-01-12T18:45:54Z

Code review (updated)

MICHAEL NOTES:

remove _value_to_engineering_notation() dead code?
investigate formatting / linter discrepancies (do you have different version of ruff, or are we not pinning etc..?)
test case having lots of inputs worth investigating (e.g. maybe break up / test 1 input at a time / etc..)

Found 7 issues, ordered by confidence:

High confidence (80+):

Unused sep_mark parameter (confidence: 100) - The parameter is documented to format digits like "1,000", but the implementation hardcodes use_seps=False which prevents any digit separation. This same pattern was previously fixed in fmt_scientific().

great-tables/great_tables/_formats.py

Lines 1111 to 1115 in cec2fb0

    
           drop_trailing_zeros=drop_trailing_zeros, 
        
           drop_trailing_dec_mark=drop_trailing_dec_mark, 
        
           use_seps=False, 
        
           sep_mark=sep_mark, 
        
           dec_mark=dec_mark,

PR needs rebase onto main (confidence: 100) - The branch predates PR feat: support polars expressions in vals functions #793 which added Polars expression support via @expressive decorator. Merging as-is will remove this functionality from all val_fmt_* functions. After rebasing, val_fmt_engineering() should also be decorated with @expressive.

great-tables/great_tables/_formats_vals.py

Lines 20 to 22 in cec2fb0


	X: TypeAlias = "Any \| list[Any] \| SeriesLike"

Medium confidence (50-79):

Redundant local import (confidence: 50) - fmt_engineering_context imports math locally at line 1077 when it's already imported at module level. A linter would catch this.

great-tables/great_tables/_formats.py

Line 1077 in cec2fb0

x: float | None,

Doesn't use existing helper (confidence: 50) - The PR implements custom engineering notation logic instead of using/enhancing _value_to_engineering_notation. However, the existing helper lacks features like decimals parameter, so there's a valid reason.

great-tables/great_tables/_formats.py

Lines 1095 to 1100 in cec2fb0

    
           # Scale `x` value by a defined `scale_by` value 
        
           x = x * scale_by 
        
           # Determine whether the value is positive 
        
           is_positive = _has_positive_value(value=x)

Lower confidence (< 50):

Import style refactor mixed with feature (confidence: 25) - vals.py imports were reorganized from grouped to individual statements. Minor style change, not a sweeping refactor.

great-tables/great_tables/vals.py

Lines 5 to 40 in cec2fb0

    
           from ._formats_vals import ( 
        
               val_fmt_bytes as fmt_bytes, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_currency as fmt_currency, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_date as fmt_date, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_engineering as fmt_engineering, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_image as fmt_image, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_integer as fmt_integer, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_markdown as fmt_markdown, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_number as fmt_number, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_percent as fmt_percent, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_roman as fmt_roman, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_scientific as fmt_scientific, 
        
           ) 
        
           from ._formats_vals import ( 
        
               val_fmt_time as fmt_time, 
        
           )

Test cases use many inputs (confidence: 25) - First test case uses 13 values when fewer would suffice. However, the "test one behavior" pattern isn't in the main CLAUDE.md.

great-tables/tests/test_formats.py

Lines 1165 to 1196 in cec2fb0

    
                   ( 
        
                       dict(decimals=2), 
        
                       [ 
        
                           829300232923103939802.4, 
        
                           492032183020.5, 
        
                           84930284002.1, 
        
                           203820929.2, 
        
                           84729202.4, 
        
                           2323435.1, 
        
                           230323.4, 
        
                           50000.01, 
        
                           1000.001, 
        
                           10.00001, 
        
                           1.2345, 
        
                           0.12345, 
        
                           0.0000123456, 
        
                       ], 
        
                       [ 
        
                           "829.30 × 10<sup style='font-size: 65%;'>18</sup>", 
        
                           "492.03 × 10<sup style='font-size: 65%;'>9</sup>", 
        
                           "84.93 × 10<sup style='font-size: 65%;'>9</sup>", 
        
                           "203.82 × 10<sup style='font-size: 65%;'>6</sup>", 
        
                           "84.73 × 10<sup style='font-size: 65%;'>6</sup>", 
        
                           "2.32 × 10<sup style='font-size: 65%;'>6</sup>", 
        
                           "230.32 × 10<sup style='font-size: 65%;'>3</sup>", 
        
                           "50.00 × 10<sup style='font-size: 65%;'>3</sup>", 
        
                           "1.00 × 10<sup style='font-size: 65%;'>3</sup>", 
        
                           "10.00", 
        
                           "1.23", 
        
                           "123.45 × 10<sup style='font-size: 65%;'>−3</sup>", 
        
                           "12.35 × 10<sup style='font-size: 65%;'>−6</sup>", 
        
                       ],

Redundant test data across cases (confidence: 25) - Multiple test cases for force_sign_m, force_sign_n use identical 7-value input lists when 2-3 values would demonstrate each feature.

great-tables/tests/test_formats.py

Lines 1250 to 1286 in cec2fb0

    
                       dict(decimals=2, force_sign_m=True), 
        
                       [-3.49e13, -3453, -0.000234, 0, 0.00007534, 82794, 7.16e14], 
        
                       [ 
        
                           "−34.90 × 10<sup style='font-size: 65%;'>12</sup>", 
        
                           "−3.45 × 10<sup style='font-size: 65%;'>3</sup>", 
        
                           "−234.00 × 10<sup style='font-size: 65%;'>−6</sup>", 
        
                           "0.00", 
        
                           "+75.34 × 10<sup style='font-size: 65%;'>−6</sup>", 
        
                           "+82.79 × 10<sup style='font-size: 65%;'>3</sup>", 
        
                           "+716.00 × 10<sup style='font-size: 65%;'>12</sup>", 
        
                       ], 
        
                   ), 
        
                   ( 
        
                       dict(decimals=2, force_sign_n=True), 
        
                       [-3.49e13, -3453, -0.000234, 0, 0.00007534, 82794, 7.16e14], 
        
                       [ 
        
                           "−34.90 × 10<sup style='font-size: 65%;'>+12</sup>", 
        
                           "−3.45 × 10<sup style='font-size: 65%;'>+3</sup>", 
        
                           "−234.00 × 10<sup style='font-size: 65%;'>−6</sup>", 
        
                           "0.00", 
        
                           "75.34 × 10<sup style='font-size: 65%;'>−6</sup>", 
        
                           "82.79 × 10<sup style='font-size: 65%;'>+3</sup>", 
        
                           "716.00 × 10<sup style='font-size: 65%;'>+12</sup>", 
        
                       ], 
        
                   ), 
        
                   ( 
        
                       dict(decimals=2, force_sign_m=True, force_sign_n=True), 
        
                       [-3.49e13, -3453, -0.000234, 0, 0.00007534, 82794, 7.16e14], 
        
                       [ 
        
                           "−34.90 × 10<sup style='font-size: 65%;'>+12</sup>", 
        
                           "−3.45 × 10<sup style='font-size: 65%;'>+3</sup>", 
        
                           "−234.00 × 10<sup style='font-size: 65%;'>−6</sup>", 
        
                           "0.00", 
        
                           "+75.34 × 10<sup style='font-size: 65%;'>−6</sup>", 
        
                           "+82.79 × 10<sup style='font-size: 65%;'>+3</sup>", 
        
                           "+716.00 × 10<sup style='font-size: 65%;'>+12</sup>", 
        
                       ],

Generated with Claude Code

_{If this review was useful, please react with 👍. Otherwise, react with 👎.}

rich-iannone · 2026-01-15T15:41:07Z

Code review (updated)

MICHAEL NOTES:

remove _value_to_engineering_notation() dead code?

Removed the unused _value_to_engineering_notation() helper function.

investigate formatting / linter discrepancies (do you have different version of ruff, or are we not pinning etc..?)

The import style changes in vals.py were caused by auto-formatting on save. I added an exclusion rule to .vscode/settings.json to circumvent this.

test case having lots of inputs worth investigating (e.g. maybe break up / test 1 input at a time / etc..)

Done. Simplified test cases significantly. Reduced from ~70 test values down to ~30 while maintaining coverage of key behaviors (positive/negative values, extreme magnitudes, zero handling, all exp_styles, force_sign options, etc.).

Found 7 issues, ordered by confidence:

High confidence (80+):

Unused sep_mark parameter (confidence: 100) - The parameter is documented to format digits like "1,000", but the implementation hardcodes use_seps=False which prevents any digit separation. This same pattern was previously fixed in fmt_scientific().

great-tables/great_tables/_formats.py

Lines 1111 to 1115 in cec2fb0

drop_trailing_zeros=drop_trailing_zeros,

drop_trailing_dec_mark=drop_trailing_dec_mark,

use_seps=False,

sep_mark=sep_mark,

dec_mark=dec_mark,

Fixed. I completely removed the sep_mark= parameter from both the fmt_engineering() and val_fmt_engineering() function signatures, docstrings, and internal code.

For engineering notation, the mantissa ranges from 1-999, so digit grouping separators have no practical effect. The sep_mark= parameter could be used for digit separators in very large exponents (but such usage is rare and outside formatting limits anyway).

Note that fmt_scientific() currently has the same issue (has a sep_mark= parameter in the signature but doesn't use it). This can be addressed in a follow-up PR.

PR needs rebase onto main (confidence: 100) - The branch predates PR feat: support polars expressions in vals functions #793 which added Polars expression support via @expressive decorator. Merging as-is will remove this functionality from all val_fmt_* functions. After rebasing, val_fmt_engineering() should also be decorated with @expressive.

great-tables/great_tables/_formats_vals.py

Lines 20 to 22 in cec2fb0

X: TypeAlias = "Any | list[Any] | SeriesLike"

Done. Branch has been rebased onto main and val_fmt_engineering() now has the @expressive decorator to support Polars expressions.

Medium confidence (50-79):

Redundant local import (confidence: 50) - fmt_engineering_context imports math locally at line 1077 when it's already imported at module level. A linter would catch this.

great-tables/great_tables/_formats.py

Line 1077 in cec2fb0

x: float | None,

Fixed. Removed the local import math line since math is already imported at the module level.

Doesn't use existing helper (confidence: 50) - The PR implements custom engineering notation logic instead of using/enhancing _value_to_engineering_notation. However, the existing helper lacks features like decimals parameter, so there's a valid reason.

great-tables/great_tables/_formats.py

Lines 1095 to 1100 in cec2fb0

# Scale `x` value by a defined `scale_by` value

x = x * scale_by

# Determine whether the value is positive

is_positive = _has_positive_value(value=x)

The existing _value_to_engineering_notation() helper was limited as it lacked support for decimals and other options. The new implementation uses _value_to_decimal_notation() which provides all the necessary formatting options. The old unused helper has been removed.

Lower confidence (< 50):

Import style refactor mixed with feature (confidence: 25) - vals.py imports were reorganized from grouped to individual statements. Minor style change, not a sweeping refactor.

great-tables/great_tables/vals.py

Lines 5 to 40 in cec2fb0

from ._formats_vals import (

val_fmt_bytes as fmt_bytes,

)

from ._formats_vals import (

val_fmt_currency as fmt_currency,

)

from ._formats_vals import (

val_fmt_date as fmt_date,

)

from ._formats_vals import (

val_fmt_engineering as fmt_engineering,

)

from ._formats_vals import (

val_fmt_image as fmt_image,

)

from ._formats_vals import (

val_fmt_integer as fmt_integer,

)

from ._formats_vals import (

val_fmt_markdown as fmt_markdown,

)

from ._formats_vals import (

val_fmt_number as fmt_number,

)

from ._formats_vals import (

val_fmt_percent as fmt_percent,

)

from ._formats_vals import (

val_fmt_roman as fmt_roman,

)

from ._formats_vals import (

val_fmt_scientific as fmt_scientific,

)

from ._formats_vals import (

val_fmt_time as fmt_time,

)

Fixed. Reverted to the grouped import style matching main branch.

Test cases use many inputs (confidence: 25) - First test case uses 13 values when fewer would suffice. However, the "test one behavior" pattern isn't in the main CLAUDE.md.

great-tables/tests/test_formats.py

Lines 1165 to 1196 in cec2fb0

(

dict(decimals=2),

[

829300232923103939802.4,

492032183020.5,

84930284002.1,

203820929.2,

84729202.4,

2323435.1,

230323.4,

50000.01,

1000.001,

10.00001,

1.2345,

0.12345,

0.0000123456,

],

[

"829.30 × 1018",

"492.03 × 109",

"84.93 × 109",

"203.82 × 106",

"84.73 × 106",

"2.32 × 106",

"230.32 × 103",

"50.00 × 103",

"1.00 × 103",

"10.00",

"1.23",

"123.45 × 10−3",

"12.35 × 10−6",

],

Addressed. Reduced test inputs to minimum needed to demonstrate each feature while still covering key edge cases (boundary values, positive/negative, zero, extreme magnitudes).

Redundant test data across cases (confidence: 25) - Multiple test cases for force_sign_m, force_sign_n use identical 7-value input lists when 2-3 values would demonstrate each feature.

great-tables/tests/test_formats.py

Lines 1250 to 1286 in cec2fb0

dict(decimals=2, force_sign_m=True),

[-3.49e13, -3453, -0.000234, 0, 0.00007534, 82794, 7.16e14],

[

"−34.90 × 1012",

"−3.45 × 103",

"−234.00 × 10−6",

"0.00",

"+75.34 × 10−6",

"+82.79 × 103",

"+716.00 × 1012",

],

),

(

dict(decimals=2, force_sign_n=True),

[-3.49e13, -3453, -0.000234, 0, 0.00007534, 82794, 7.16e14],

[

"−34.90 × 10+12",

"−3.45 × 10+3",

"−234.00 × 10−6",

"0.00",

"75.34 × 10−6",

"82.79 × 10+3",

"716.00 × 10+12",

],

),

(

dict(decimals=2, force_sign_m=True, force_sign_n=True),

[-3.49e13, -3453, -0.000234, 0, 0.00007534, 82794, 7.16e14],

[

"−34.90 × 10+12",

"−3.45 × 10+3",

"−234.00 × 10−6",

"0.00",

"+75.34 × 10−6",

"+82.79 × 10+3",

"+716.00 × 10+12",

],

Addressed. Reduced force_sign_m, force_sign_n tests from 7 values to 2-3 values each, covering positive, negative, and zero cases.

machow

Thanks this looks great! The one final thing I might suggest from reading the docstring

I wonder if it'd be helpful to frontload an example, like...

With numeric values in a table, we can perform formatting so that the targeted values are rendered in engineering notation. For example, the number 0.0000345 in engineering notation can be 34.50 x 10^-6. Engineering notation represents numbers as a mantissa (m) and an exponent (n), in the form m x 10^n or mEn. ...

Essentialy, moving the example from the end to the front, so it becomes a worked example

rich-iannone added 5 commits October 19, 2025 20:55

Add engineering notation formatting method

c88469e

Update _formats_vals.py

fa02a99

Update vals.py

c3886c6

Update test_formats.py

e7f0d47

Add GT.fmt_engineering to reference API

26dbc84

github-actions bot temporarily deployed to pr-786 October 20, 2025 01:17 Destroyed

rich-iannone added 2 commits October 19, 2025 21:19

Add tests for some fmt_engineering() edge cases

134089d

Add tests for engineering notn formatter function

cec2fb0

github-actions bot temporarily deployed to pr-786 October 20, 2025 01:31 Destroyed

github-actions bot temporarily deployed to pr-786 October 20, 2025 01:36 Destroyed

rich-iannone marked this pull request as ready for review October 20, 2025 01:51

rich-iannone requested a review from machow as a code owner October 20, 2025 01:51

rich-iannone changed the title ~~Feat fmt engineering~~ feat: add fmt_engineering() Oct 20, 2025

Merge remote-tracking branch 'origin/main' into feat-fmt-engineering

6fca305

github-actions bot temporarily deployed to pr-786 January 15, 2026 15:01 Destroyed

rich-iannone added 6 commits January 15, 2026 10:27

Refactor vals.py imports and update Ruff config

550c1bd

Remove redundant import in fmt_engineering_context()

1f75793

Remove unused engineering notation function

c100ec6

Remove sep_mark parameter from engineering format functions

7f5a65d

Reorder and clean up imports in _formats_vals.py

f994045

Simplify engineering format test cases

6771596

github-actions bot temporarily deployed to pr-786 January 15, 2026 15:42 Destroyed

Remove sep_mark arg from eng formatters

69e8f85

github-actions bot temporarily deployed to pr-786 January 15, 2026 16:00 Destroyed

machow approved these changes Jan 15, 2026

View reviewed changes

Include simple example to start off section

0692903

github-actions bot deployed to pr-786 January 16, 2026 14:44 View deployment

rich-iannone merged commit 6b224c0 into main Jan 16, 2026
14 checks passed

rich-iannone deleted the feat-fmt-engineering branch January 16, 2026 14:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add `fmt_engineering()` #786

feat: add `fmt_engineering()` #786

Uh oh!

rich-iannone commented Oct 20, 2025

Uh oh!

codecov bot commented Oct 20, 2025 •

edited

Loading

Uh oh!

machow commented Jan 12, 2026 •

edited

Loading

Uh oh!

rich-iannone commented Jan 15, 2026 •

edited

Loading

Code review (updated)

Uh oh!

machow left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add fmt_engineering() #786

feat: add fmt_engineering() #786

Uh oh!

Conversation

rich-iannone commented Oct 20, 2025

Uh oh!

codecov bot commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

machow commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code review (updated)

Uh oh!

rich-iannone commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code review (updated)

Uh oh!

machow left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add `fmt_engineering()` #786

feat: add `fmt_engineering()` #786

codecov bot commented Oct 20, 2025 •

edited

Loading

machow commented Jan 12, 2026 •

edited

Loading

rich-iannone commented Jan 15, 2026 •

edited

Loading

machow left a comment •

edited

Loading